Skip to main content

Arbitrary Message Bridge

The native Arbitrary Message Bridge (AMB) allows user to send arbitrary data between Gnosis Chain and Ethereum. This allows Gnosis contracts to send data and trigger contract functions on Ethereum and other chains, and vice versa.

The AMB is a key bridge primitive that is used inside higher-order bridges like the Omnibridge native token bridge, and is part of the Tokenbridge Architecture.

Due to the light client finality requirements (at least 23mins on Ethereum), the transactions will take approx. 30mins to be signed by the bridge. However, users can still use 3rd party bridges (Jumper.exchange, Connext, Hop) without any impact.

Overview​

Detail
Frontend URLN/A
Trust Model4-of-7 Validator Multisig
Governance8-of-16 Multisig
Governance ParametersValidators
Bug Bountyup to $2m
Bug ReportingImmunefi

Contracts​

Ethereum

ContractAddress
Omnibridge Multi-Token Mediator0x88ad09518695c6c3712AC10a214bE5109a655671
AMB (Foreign)0x4C36d2919e407f0Cc2Ee3c993ccF8ac26d9CE64e
AMB/OmniBridge wETH Router Helper0xa6439Ca0FCbA1d0F80df0bE6A17220feD9c9038a

Bridge Validators​

Bridge Governance​

How it works​

Terminology​

  • Home (Native) Network: Gnosis Chain.
  • Foreign Network: Ethereum.
  • Originating Contract: An arbitrary contract where the message originates, typically this is where the user interacts and requests for a function to be invoked on another network. For example, Omnibridge is the originating contract that use AMB contract as data messaging layer.

Call a cross-chain method via AMB:​

function requireToPassMessage (address _contract,
                                bytes _data,
                                uint256 _gas) external;
paramdetails
_contractaddress of contract on other network
_dataencoded bytes of the method selector and the params that will be called in the contract on the other side
_gasgas to be provided in execution of the method call on the other side

Ethereum to Gnosis Chain​

  1. User calls foo() on the originating contract
  2. Originating contract calls requireToPassMessage() on Foreign AMB contract, and encodes foo(), target address, and gas limit used on the other chain for executing a message.
  3. UserRequestForAffirmation(bytes32 indexed messageId, bytes encodedData) event is emitted from Foreign AMB contract, and listening bridge validators relay the message to the Home side where signatures are collected by calling Home AMB executeAffirmation(bytes message), where message parameter is the encodedData from UserRequestForAffirmation event. Hashi acts as an additional bridge valdiator who validates transactions but no actually calling executeAffirmation on Home AMB. For more details about how Hashi works in this case, check out here
  4. Once enough signatures has been collected by bridge valdiators, the transaction will emit CollectedSignatures (address authorityResponsibleForRelay, bytes32 messageHash, uint256 NumberOfCollectedSignatures) and calls foo() on the target contract.

Gnosis Chain to Ethereum​

  1. User calls foo() on an originating contract
  2. Originating contract calls requireToPassMessage() on Home Bridge contract, and encodes foo(), target address, and gas limit used on the other chain for executing a message.
  3. Signatures are collected from validators by calling submitSignatures(), and once enough are collected CollectedSignatures() event is emitted. Hashi acts as an additional bridge valdiator who validates transactions but no actually calling executeAffirmation on Home AMB. For more details about how Hashi works in this case, check out here
  4. Anyone can execute the call by calling executeSignatures(bytes message, bytes signatures) on Foreign AMB. To fetch the calldata for executeSignatures function, please follow the guideline below.
  5. Foreign AMB contract decodes the message and calls foo() on target contract

How to call executeSignatures on Foreign AMB (Ethereum)​

When the transaction is initiated from Home Network (Gnosis Chain), one has to claim the transaction on Ethereum explicitly. Here is how you can fetch the calldata required to call Foreign AMB to claim the transaction.

  1. Find the originating transaction on Gnosis Chain that interact with the Home AMB, and look for UserRequestForSignature(bytes32 indexed messageId, bytes encodedData). Example
  2. Go to AMB Helper contract on Gnosis Chain, paste the encodedData from UserReqeustForSignature into getSignatures(bytes _message) (the message starts with 0x0005). Fetch the return value from getSignatures.
  3. On Foreign AMB, call executeSigantures(bytes _data, bytes _signatures), where _data is the encodedData from UserRequestForSignature and _signatures is from the return value of getSignatures method. Please make sure that the caller account has enough ETH for the gas fee.

How to check if AMB is down (not relaying message)​

In certain circumstances, i.e. hardfork, AMB will be planned for downtime (not relaying message) to ensure security of the bridge. Planned downtime will be announced in public channel like Discord and Twitter, prior to the event.
There is also another way to check whether the AMB is down or not by reading maxGasPerTx value on AMB contract.

In the current configuration, maxGasPerTx is set to 4000000 on Ethereum and 2000000 on Gnosis Chain.

The AMB is down when maxGasPerTx is set to 0, only by owner of the contract.

By setting maxGasPerTx to 0, the condition in _sendMessage() will not pass, meaning, the bridge is down/stopped.

Security Considerations for Receiving a Call​

ConcernRemediation
AuthorizationCheck the address of invoking contract using messageSender()
AuthorizationCheck that msg.sender is the address of the bridge contract
Replay AttacktransactionHash() allows for checking of a hash of the transaction that invoked the requireToPassMessage() call. The invoking contract (in some cases, the mediator contract) is responsible for providing a unique sequence (can be a nonce) as part of the _data param in the requireToPassMessage() function call

AMB Components​

ComponentDescription
System ContractsAMB Implementation Contracts (Home Bridge and Foreign Bridge), Governance Multisigs, gas limit helpers, failed call management helpers (for when gas estimate was insufficient), and fee management helpers to collect fees
Bridge validatorContainerized microservices that listen for on-chain events and send confirmations to relay messages. More on them here.
DevOpsBridge validator,Bridge UI, docker compose, ansible playbooks
dApp Contractsextensions (pair mediator contracts on both sides of the AMB), such as the Omnibridge

Use Cases of AMB​

  • ERC-to-ERC Bridges: AMB-ERC-TO-ERC mode enables the transfer of ERC tokens to the Foreign Mediator, which will interact with Foreign AMB Bridge to mint wrapped ERC-667 tokens on the Home Network. Complimentarily, the mode enables the transfer ERC20 or ERC-667 tokens to the Home Mediator, which will interact with Home AMB Bridge to unlock ERC20 tokens on the Foreign network. This is used by the Omnibridge.
  • ERC-to-Native Bridges: ERC-TO-NATIVE mode enables the user to send ERC20 tokens to the Foreign Bridge and receive native coins from the Home Bridge Complimentarily, then can send native coins to the Home Bridge to unlock ERC20 tokens from the Foreign Bridge. The home network nodes must support a consensus engine that allows using a smart contract for block reward calculation. This mode is used by the xDai Bridge
  • Message Passing: ARBITRARY-MESSAGE mode enables the capability to invoke a Home/Foreign Bridge contract to send a message that will be executed on the other Network. This can be an arbitrary contract method invocation.

Resources​